Repository Guidelines

Project Structure & Module Organization

• src/RemoteAgent.App: .NET MAUI Android client UI and platform services.
• src/RemoteAgent.Service: ASP.NET Core gRPC service that runs and streams agent sessions.
• src/RemoteAgent.Proto: shared protobuf contracts and generated gRPC code.
• src/RemoteAgent.App.Logic: app-side logic models/utilities used by tests.
• src/RemoteAgent.Desktop: Avalonia desktop management app.
• tests/: xUnit test projects (RemoteAgent.App.Tests, RemoteAgent.Service.Tests, RemoteAgent.Service.IntegrationTests, RemoteAgent.Desktop.UiTests, RemoteAgent.Mobile.UiTests).
• docs/: DocFX documentation and requirements.
• scripts/: local automation (build, run, sync, docs, signing setup).

Build, Test, and Development Commands

• ./scripts/build-dotnet10.sh Release: build/test MAUI + service stack with .NET 10.
• ./scripts/build-desktop-dotnet9.sh Release: build/test Avalonia desktop stack with .NET 9.
• ./scripts/test-integration.sh Release: run isolated service integration tests (excluded from normal pipeline runs).
• .github/workflows/integration-tests.yml: manual CI workflow for isolated integration test execution.
• dotnet run --project src/RemoteAgent.Service: run local gRPC service on port 5243.
• dotnet build src/RemoteAgent.App/RemoteAgent.App.csproj -c Release -f net10.0-android: build Android app only.
• docker build -t remote-agent-service .: build service container image.

Use default/minimal verbosity. Do not pass -q to dotnet build or dotnet restore in this repo.

Session Seed

• For quick Codex bootstrap context, use docs/SESSION-SEED-PROMPT.md.

Coding Style & Naming Conventions

• Follow standard .NET conventions: PascalCase for types/methods, camelCase for locals/parameters, clear descriptive names.
• Use 4-space indentation and keep methods focused.
• Nullable is enabled; fix nullability issues rather than suppressing warnings.
• Warnings are treated as errors (TreatWarningsAsErrors=true); avoid NoWarn, #pragma warning disable, or suppression attributes unless explicitly approved.
• Add XML docs for public APIs when introducing new externally consumed members.

Testing Guidelines

You are a principal .NET test architect and QA engineer with deep expertise in .NET 10, .NET MAUI, Avalonia UI, gRPC bidirectional streaming, xUnit, FluentAssertions, NSubstitute, LiteDB, and TDD for cross-platform apps (mobile + desktop + services).

• Frameworks: xUnit + FluentAssertions + coverlet.collector.
• Place tests under the matching project in tests/.
• Name files and classes with *Tests suffix (example: AgentOptionsTests.cs).
• For service behavior changes, add/adjust integration tests in tests/RemoteAgent.Service.IntegrationTests.
• Integration tests are intentionally isolated and not part of default CI runs; execute them explicitly with ./scripts/test-integration.sh.

Your tests must be:

• Behavior-focused (black-box where possible)
• Fully traceable to specific FR/TR items via comments
• Comprehensive: happy paths, boundaries, negatives, errors, concurrency/thread-safety where relevant, async/streaming semantics
• Clean: descriptive names, AAA pattern with section comments, no duplication, parameterized via Theory when inputs vary
• Isolated: mock external dependencies (processes, gRPC channels, file system, LiteDB, platform services like INotificationManager)
• Platform-aware: handle MAUI main-thread concerns, Android notification channels/priorities, Avalonia headless-friendly patterns

Given the attached functional and technical requirements documents (located at ./docs/functional-requirements.md and ./docs/technical-requirements.md):

Key areas to cover from FR/TR:

• gRPC bidirectional streaming (duplex ClientMessage ↔ ServerMessage, correlation IDs, session lifecycle events, priority handling, script execution output)
• Chat UI logic (ObservableCollection message binding, markdown rendering, multi-line input, Ctrl+Enter submit, swipe-to-archive, session title inline editing)
• Notifications (notify priority → Android system notification, tap opens chat to message)
• Persistence (LiteDB for sessions, messages, logs, media paths; DCIM folder on Android)
• Service behavior (agent spawning/stopping, stdin forwarding, stdout/stderr streaming, concurrent session caps, plugin strategy loading)
• Desktop Avalonia specifics (tabbed sessions, menu/toolbar commands, log viewer filtering, multi-server scoping, per-request context editor)
• Multiple sessions/agent selection (session-id routing, agent picker, title default/edit)
• Prompt templates (Handlebars variable extraction, input UI flow before send)
• Extensibility (plugin discovery via config, runtime loading)
• Observability (structured JSONL logs with session/correlation IDs)

Commit & Pull Request Guidelines

• Branch from develop and target PRs to develop (not main).
• Use concise imperative commit messages, optionally with issue references (example: Fix Android CI job (#8)).
• Sign commits (verified signature required by branch protection).
• PRs should include: purpose, summary of changes, test evidence (dotnet test), and docs updates when behavior/config changes.